@opentelemetry/semantic-conventions
Advanced tools
The @opentelemetry/semantic-conventions package provides standardized naming and semantic conventions for attributes in OpenTelemetry. These conventions help ensure that telemetry data is consistent, interpretable, and analyzable across different systems and services. The package includes constants for resource attributes, span attributes, and event names that are recommended by the OpenTelemetry specification.
Resource Attributes
Defines standard attributes to be used for service resources, allowing you to annotate your telemetry data with information about the service instance.
{"service.name": 'my-service', "service.version": '1.0.0', "service.instance.id": 'instance-123'}Span Attributes
Provides a set of standard attributes for spans, which represent individual operations within a trace. These attributes can be used to add metadata about the operation, such as HTTP method, URL, and status code.
{"http.method": 'GET', "http.url": 'https://example.com', "http.status_code": 200}Event Names
Includes standardized event names for logging exceptions, messages, and metrics within spans. This helps in categorizing and querying telemetry events.
"exception", "message", "metric"Elastic APM Node.js Agent is a real user monitoring library that provides similar functionality to OpenTelemetry. It allows you to instrument your Node.js applications to track performance metrics and errors. While it also adheres to certain conventions, it is tailored to work with the Elastic Stack, and may not be as flexible as OpenTelemetry in terms of vendor neutrality.
Jaeger client libraries provide features for distributed tracing similar to OpenTelemetry. They offer their own set of conventions for tracing data. While Jaeger is compatible with OpenTelemetry through exporters, its native conventions are not the same as those defined by OpenTelemetry's semantic conventions.
Semantic Convention constants for use with the OpenTelemetry SDK/APIs. This document defines standard attributes for traces.
npm install --save @opentelemetry/semantic-conventions
This package has 2 separate entry-points:
@opentelemetry/semantic-conventions, includes only stable semantic conventions.
This entry-point follows semantic versioning 2.0: it will not include breaking changes except with a change in the major version number.@opentelemetry/semantic-conventions/incubating, contains unstable semantic conventions (sometimes called "experimental") and, for convenience, a re-export of the stable semantic conventions.
This entry-point is NOT subject to the restrictions of semantic versioning and MAY contain breaking changes in minor releases.Exported constants follow this naming scheme:
ATTR_${attributeName} for attributesMETRIC_${metricName} for metric names${attributeName}_VALUE_{$enumValue} for enumerationsThe ATTR, METRIC, and VALUE static strings were used to facilitate readability and filtering in auto-complete lists in IDEs.
npm install --save @opentelemetry/semantic-conventions
import {
ATTR_NETWORK_PEER_ADDRESS,
ATTR_NETWORK_PEER_PORT,
ATTR_NETWORK_PROTOCOL_NAME,
ATTR_NETWORK_PROTOCOL_VERSION,
NETWORK_TRANSPORT_VALUE_TCP,
} from '@opentelemetry/semantic-conventions';
const span = tracer.startSpan(spanName, spanOptions)
.setAttributes({
[ATTR_NETWORK_PEER_ADDRESS]: 'localhost',
[ATTR_NETWORK_PEER_PORT]: 8080,
[ATTR_NETWORK_PROTOCOL_NAME]: 'http',
[ATTR_NETWORK_PROTOCOL_VERSION]: '1.1',
[ATTR_NETWORK_TRANSPORT]: NETWORK_TRANSPORT_VALUE_TCP,
});
npm install --save-exact @opentelemetry/semantic-conventions
Note: Because the "incubating" entry-point may include breaking changes in minor versions, it is recommended that users of unstable semconv values either:
npm install --save-exact ...), orimport {
ATTR_PROCESS_COMMAND,
ATTR_PROCESS_COMMAND_ARGS,
ATTR_PROCESS_COMMAND_LINE,
} from '@opentelemetry/semantic-conventions/incubating';
const span = tracer.startSpan(spanName, spanOptions)
.setAttributes({
[ATTR_PROCESS_COMMAND]: 'cat',
[ATTR_PROCESS_COMMAND_ARGS]: ['file1', 'file2'],
[ATTR_CONTAINER_COMMAND_LINE]: 'cat file1 file2',
});
There are two main types of deprecations in this package:
http.url span attribute in favor of url.full. When using this JS package, that appears as a deprecation of the ATTR_HTTP_URL export in favour of ATTR_URL_FULL.ATTR_HTTP_URL instead of SEMATTRS_HTTP_URL. The two older forms are still included in 1.x versions of this package for backwards compatibility. The rest of this section shows how to migrate to the latest form.SEMATTRS_*, SEMRESATTRS_*, ...Deprecated as of @opentelemetry/semantic-conventions@1.26.0.
Before v1.26.0, constants for each semconv attribute were exported, prefixed with SEMRESATTRS_ (if defined as a Resource Attribute) or SEMATTRS_. As well, constants were exported for each value in an enumeration, of the form ${attributeName}VALUES_${enumValue}. For example:
Deprecated usage:
import {
SEMRESATTRS_SERVICE_NAME,
SEMATTRS_HTTP_ROUTE,
SEMATTRS_DB_SYSTEM,
DBSYSTEMVALUES_POSTGRESQL
} from '@opentelemetry/semantic-conventions';
// 'service.name' resource attribute
console.log(SEMRESATTRS_SERVICE_NAME); // migrate to 'ATTR_SERVICE_NAME'
// 'http.route' attribute
console.log(SEMATTRS_HTTP_ROUTE); // migrate to 'ATTR_HTTP_ROUTE'
// 'db.system' attribute
console.log(SEMATTRS_DB_SYSTEM); // migrate to 'ATTR_DB_SYSTEM' (in incubating [*])
// 'postgresql' enum value for 'db.system' attribute
console.log(DBSYSTEMVALUES_POSTGRESQL); // migrate to 'DB_SYSTEM_VALUE_POSTGRESQL' (in incubating [*])
See Migrated usage below.
SemanticAttributes.*, SemanticResourceAttributes.*, ...Deprecated as of @opentelemetry/semantic-conventions@1.0.0.
Before v1.0.0, constants were exported in namespace objects SemanticResourceAttributes and SemanticAttributes, and a namespace object for enumerated values for some fields (e.g. DbSystemValues for values of the 'db.system' enum). For example:
Deprecated usage:
import {
SemanticAttributes,
SemanticResourceAttributes,
DbSystemValues,
} from '@opentelemetry/semantic-conventions';
// 'service.name' resource attribute
console.log(SemanticResourceAttributes.SERVICE_NAME); // migrate to 'ATTR_SERVICE_NAME'
// 'http.route' attribute
console.log(SemanticAttributes.HTTP_ROUTE); // migrate to 'ATTR_HTTP_ROUTE'
// 'db.system' attribute
console.log(SemanticAttributes.DB_SYSTEM); // migrate to 'ATTR_DB_SYSTEM' (in incubating [*])
// 'postgresql' enum value for 'db.system' attribute
console.log(DbSystemValues.POSTGRESQL); // migrate to 'DB_SYSTEM_VALUE_POSTGRESQL' (in incubating [*])
See Migrated usage below.
import {
ATTR_SERVICE_NAME,
ATTR_HTTP_ROUTE,
METRIC_HTTP_CLIENT_REQUEST_DURATION
} from '@opentelemetry/semantic-conventions';
import {
ATTR_DB_SYSTEM,
DB_SYSTEM_VALUE_POSTGRESQL
} from '@opentelemetry/semantic-conventions/incubating';
console.log(ATTR_SERVICE_NAME); // 'service.name'
console.log(ATTR_HTTP_ROUTE); // 'http.route'
// Bonus: the older exports did not include metric names from semconv.
// 'http.client.request.duration' metric name
console.log(METRIC_HTTP_CLIENT_REQUEST_DURATION);
console.log(ATTR_DB_SYSTEM); // 'db.system'
// 'postgresql' enum value for 'db.system' attribute
console.log(DB_SYSTEM_VALUE_POSTGRESQL);
The first three fields in the preceding code sample ('service.name', 'http.route', 'http.client.request.duration') are stable in semantic conventions, the latter two are not. Version 1.26.0 of this package separated stable and unstable into separate module entry points: stable conventions are imported from '@opentelemetry/semantic-conventions' and unstable from '@opentelemetry/semantic-conventions/incubating'. The name "incubating" is suggested by the Semantic Conventions.
It is recommended that if you are using exports from incubating, that you pin the version in your package.json dependencies (e.g. via npm install --save-exact @opentelemetry/semantic-conventions) or that you copy the relevant definitions into your code base. This is because the removal of exports from the incubating entry point is not considered a breaking change and hence can happen in a minor version.
Note: The incubating entry point also exports all stable fields, so the above example could be changed to import all five constants from '@opentelemetry/semantic-conventions/incubating'.
Apache 2.0 - See LICENSE for more information.
1.28.0
feat(sdk-metrics, sdk-trace): add mergeResourceWithDefaults flag, which allows opting-out of resources getting merged with the default resource #4617
true (no change in behavior)false will become the default behavior in the next major version in order to comply with specification requirementsfeat(sdk-trace-base): add spanProcessors property in TracerConfig interface. #5138 @david-luna
PeriodicExportingMetricReader when async resource attributes have not yet settled #5119 @pichlermarcFAQs
OpenTelemetry semantic conventions
The npm package @opentelemetry/semantic-conventions receives a total of 18,331,575 weekly downloads. As such, @opentelemetry/semantic-conventions popularity was classified as popular.
We found that @opentelemetry/semantic-conventions demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.